---
title: Providers
---

Now that we have installed [Riverpod], let's talk about "providers".

Providers are the most important part of a [Riverpod] application.  
A provider is an object that encapsulate a piece of state and allows listening
to that state.

## Why use providers?

By wrapping a piece of state in a provider, this:

- Allows easily accessing that state in multiple locations.  
  Providers are a complete replacement for patterns like Singletons,
  Service Locators, Dependency Injection or InheritedWidgets.

- Simplifies combining this state with others.  
  Ever struggled merging multiple objects into one? This scenario is built
  directly inside providers, with a simple syntax.

- Enables performance optimisations.  
  Whether for filtering widget rebuilds or for caching expensive state computations;
  providers ensure that only what is impacted by a state change is recomputed.

- Increases the testability of your application.  
  With providers, you do not need complex `setUp`/`tearDown` steps. Furthermore,
  any provider can be overridden to behave differently during test, which
  allows easily testing a very specific behavior.

- Easily integrate with advanced features, such as logging or pull-to-refresh.

## Creating a provider

Providers come in many variants, but they all work the same way.

The most common usage is to declare them as global constant like so:

```dart
final myProvider = Provider((ref) {
  return MyValue();
});
```

:::note
Do not be afraid by the global aspect of providers.  
Providers are fully immutable. Declaring a provider is no different from declaring
a function, and is testable and maintainable.
:::

This snippet consist of three components:

- `final myProvider`, the declaration of a variable.  
  This variable is what we will use in the future to read the state of our provider.
  It should always be immutable.

- `Provider`, the provider that we decided to use.  
  [Provider] is the most basic of all providers. It exposes an object that never
  changes.  
  We could replace [Provider] with other providers like [StreamProvider] or
  [StateNotifierProvider], to change how the value is interacted with.

- A function that creates the shared state.  
  That function will always receive an object called `ref` as a parameter. This object
  allows us to read other providers or to perform some operations when the state
  of our provider will be destroyed.

The type of the object created by the function passed to a provider depends on
the provider used.  
For example, the function of a [Provider] can create any object.
On the other hand, [StreamProvider]'s callback will be expected to return a [Stream].

:::info
You can declare as many providers as you, want without limitations.  
As opposed to when using `package:provider`, in [Riverpod] we can have two
providers expose a state of the same "type":

```dart
final cityProvider = Provider((ref) => 'London');
final countryProvider = Provider((ref) => 'England');
```

The fact that both providers create a `String` does not cause any problem.
:::

:::caution
For providers to work, you must add [ProviderScope] at the root of your
Flutter applications:

```dart
void main() {
  runApp(ProviderScope(child: MyApp()));
}
```

:::

## Performing actions before the state destruction

In some cases, the state of a provider may get destroyed or re-created.
A common use-case in those situations is to perform a cleanup before the state of a provider
is destroyed, such as closing a `StreamController`.

This is done using the `ref` object, which is passed to the callback of all providers, using its [onDispose] method.

The following example uses [onDispose] to close a `StreamController`:

```dart
final example = StreamProvider.autoDispose((ref) {
  final streamController = StreamController<int>();

  ref.onDispose(() {
    // Closes the StreamController when the state of this provider is destroyed.
    streamController.close();
  });

  return streamController.stream;
});
```

:::note
Depending on the provider used, it may already take care of the clean-up process.  
For example, [StateNotifierProvider] will call the `dispose` method of a `StateNotifier`.
:::

## Provider Modifiers

All Providers have a built-in way to add extra functionalities to your different providers.

They may add new features to the `ref` object or change slightly how the provider
is consumed.  
Modifiers can be used on all providers, with a syntax similar to named constructor:

```dart
final myAutoDisposeProvider = StateProvider.autoDispose<String>((ref) => 0);
final myFamilyProvider = Provider.family<String, int>((ref, id) => '$id');
```

At the moment, there are two modifiers available:

- [`.autoDispose`](/docs/concepts/modifiers/auto_dispose), which will make the provider automatically destroy its state
  when it is no-longer listened.
- [`.family`](/docs/concepts/modifiers/family), which allows creating a provider from external parameters.

:::note
A provider can use multiple modifiers at once:

```dart
final userProvider = FutureProvider.autoDispose.family<User, int>((ref, userId) async {
  return fetchUser(userId);
});
```

:::

That's it for this guide!

You can continue with [How to read a provider](/docs/concepts/reading).
Alternatively, you can see [How to combine providers](/docs/concepts/combining_providers).

[get_it]: http://pub.dev/packages/get_it
[inheritedwidget]: https://api.flutter.dev/flutter/widgets/InheritedWidget-class.html
[stream]: https://api.dart.dev/stable/2.8.4/dart-async/Stream-class.html
[ondispose]: https://pub.dev/documentation/riverpod/latest/all/ProviderReference/onDispose.html
[riverpod]: https://github.com/rrousselgit/river_pod
[hooks_riverpod]: https://pub.dev/packages/hooks_riverpod
[flutter_riverpod]: https://pub.dev/packages/flutter_riverpod
[flutter_hooks]: https://github.com/rrousselGit/flutter_hooks
[provider]: https://pub.dev/documentation/riverpod/latest/all/Provider-class.html
[streamprovider]: https://pub.dev/documentation/riverpod/latest/all/StreamProvider-class.html
[statenotifierprovider]: https://pub.dev/documentation/riverpod/latest/all/StateNotifierProvider-class.html
[providerscope]: https://pub.dev/documentation/flutter_riverpod/latest/all/ProviderScope-class.html
